home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / cmds / perl / doc / refbase.tex < prev    next >
Encoding:
Text File  |  1991-07-29  |  46.4 KB  |  1,575 lines
  1. % refmaster.tex -- Perl Reference Guide
  2. % SCCS Status     : @(#)@ refmaster    4.2.1
  3. % Author          : Johan Vromans
  4. % Created On      : Wed Jul 10 18:26:19 1991
  5. % Last Modified By: Johan Vromans
  6. % Last Modified On: Mon Jul 15 23:12:27 1991
  7. % Update Count    : 3
  8. % Status          : OK?
  9. %
  10. %%%%%%%%%%%%%%%% Copyright %%%%%%%%%%%%%%%%
  11. %
  12. % The Perl Reference Guide and its associated files are 
  13. %
  14. % Copyright 1989, 1990, 1991 Johan Vromans.
  15. %
  16. % They may be used and reproduced under the terms of the
  17. % GNU Public Licence. A copy of this licence should have 
  18. % been included in your Perl source kit.
  19. %
  20. %%%%%%%%%%%%%%%% Disclaimer %%%%%%%%%%%%%%%%
  21. %
  22. % I'm not a TeX wizard. I stole some of the ideas from 
  23. % Raymond Chen <raymond@math.berkeley.edu> and others.
  24. %
  25. %%%%%%%%%%%%%%%% Start of code %%%%%%%%%%%%%%%%
  26. %
  27. \documentstyle{refbase}
  28.  
  29. \begin{document}
  30.  
  31.  
  32. \begin{titlepage}
  33.  
  34. \hbox{ }
  35. \end{titlepage}
  36.  
  37. \begin{titlepage}
  38. \addtolength{\evensidemargin}{2cm}
  39. \addtolength{\textwidth}{-2.1cm}
  40. \vspace*{2.5cm}
  41.  
  42. \vbox{{\xviipt\sl Perl Reference Guide}
  43.       {\rule[0.3cm]{\textwidth}{0.25pt}}}
  44.  
  45. {\bf for Perl version 4.010}
  46.  
  47. \vskip1cm
  48. Perl program designed and created by \\
  49. Larry Wall \<lwall@netlabs.com\>
  50.  
  51. \vskip1cm
  52. Reference guide designed and created by \\
  53. Johan Vromans \<jv@mh.nl\>
  54.  
  55. \vskip1.5cm
  56. \vbox{{\xviipt\sl Contents}
  57.       {\rule[0.3cm]{\textwidth}{0.25pt}}}
  58.  
  59. \newcounter{xx}
  60. \begin{list}{\thexx.}
  61. {\setlength{\topsep}{0pt plus 1pt}
  62.  \setlength{\itemsep}{0pt plus 1pt}
  63.  \setlength{\parsep}{0pt plus 1pt}
  64.  \usecounter{xx}}
  65. \item Command line options
  66. \item Literals
  67. \item Variables
  68. \item Statements
  69. \item Flow control
  70. \item Operators
  71. \item File test operators
  72. \item Arithmetic functions
  73. \item Conversion functions
  74. \item Structure conversion
  75. \item String functions
  76. \item Array and list functions
  77. \item File operations
  78. \item Directory reading routines
  79. \item Input / Output
  80. \item Search and replace functions
  81. \item System interaction
  82. \item Networking
  83. \item SystemV IPC
  84. \item Miscellaneous
  85. \item Formats
  86. \item Info from system files
  87. \item Regular expressions
  88. \item Special variables
  89. \item Special arrays
  90. \item The perl debugger
  91. \end{list}
  92. \vskip1cm
  93. {\catcode`\%=\other \ixpt Rev. \perlrev}
  94. \end{titlepage}
  95.  
  96. \vbox{{\xviipt\sl Conventions}
  97.       {\rule[0.3cm]{\textwidth}{0.25pt}}}
  98.  
  99. \begin{enum}{2cm}
  100. \Xi{|fixed|} denotes literal text.
  101.  
  102. \Xi{<this>} means variable text, i.e. things you must fill in.
  103.  
  104. \Xi{<this>\dag} means that <this> will default to |$_| if omitted.
  105.  
  106. \Xi{\kwd{word}} is a keyword, i.e. a word with a special meaning.
  107.  
  108. \Xi{\fbox{<ret>}} denotes pressing a keyboard key.
  109.  
  110. \Xi{[\ldots]} denotes an optional part.
  111.  
  112. \Xi{(\ldots)*} means that the parentheses may be omitted.
  113.  
  114. \end{enum}
  115. \section{Command line options} 
  116.  
  117. \begin{enum}{1cm}
  118.  
  119. \Xi{|-a|} turns on autosplit mode when used with |-n| or
  120. |-p|. Splits to |@F|.
  121.  
  122. \Xi{|-c|} checks syntax but does not execute.
  123.  
  124. \Xi{|-d|} runs the script under the debugger. Use |-de 0| to
  125. start the debugger without a script.
  126.  
  127. \Xi{|-D| <number>} sets debugging flags. 
  128.  
  129. \Xi{|-e| <commandline>} may be used to enter one line of
  130. script. Multiple |-e| commands may be given to build up a
  131. multi-line script.
  132.  
  133. \Xi{|-i| <ext>} files processed by the |<>| construct are
  134. to be edited in-place.
  135.  
  136. \Xi{|-I| <dir>} with |-P|: tells the C preprocessor where
  137. to look for include files. The directory is prepended to |@INC|.
  138.  
  139. \Xi{|-L| <octnum>} enables automatic line ending processing.
  140.  
  141. \Xi{|-n|} assumes an input loop around your script. Lines are not
  142. printed.
  143.  
  144. \Xi{|-p|} assumes an input loop around your script. Lines are
  145. printed.
  146.  
  147. \Xi{|-P|} runs the C preprocessor on the script before
  148. compilation by perl.
  149.  
  150. \Xi{|-s|} interprets ``|-xxx|'' on the command line as
  151. switches and sets the corresponding variables \$|xxx| in the script.
  152.  
  153. \Xi{|-S|} uses the |PATH| environment variable to search for
  154. the script.
  155.  
  156. \Xi{|-u|} dumps core after compiling the script. To be used with
  157. the {\it undump\/} program (where available).
  158.  
  159. \Xi{|-U|} allows perl to do unsafe operations.
  160.  
  161. \Xi{|-v|} prints the version and patchlevel of your perl
  162. executable.
  163.  
  164. \Xi{|-w|} prints warnings about possible spelling errors and
  165. other error-prone constructs in the script.
  166.  
  167. \Xi{|-x|} extracts perl program from input stream.
  168.  
  169. \Xi{|-0| <val>} (that's the number zero) designates an
  170. initial value for the record terminator \$|/|.
  171. See also |-L|.
  172.  
  173. \end{enum}
  174. \makeuppage
  175. \section{Literals} 
  176.  
  177. Numeric: |123  123.4  5E-10  0xff| (hex)|  0377| (octal).
  178.  
  179. \hangindent=2cm\hangafter=1
  180. String: |'abc'| literal string, no variable interpolation nor
  181. escape characters.
  182. \newline Also: |q/abc/|.
  183. \newline (Almost any pair of delimiters can be used instead of |/.../|.)
  184.  
  185. \hangindent=2cm\hangafter=1
  186. \makebox[1cm]{}|"abc"|
  187. Variables are interpolated and escape sequences are processed. 
  188. \newline Also: |qq/abc/|.
  189. \newline Escape sequences: |\t| (Tab), |\n| (Newline), |\r| (Return),
  190. |\f| (Formfeed), |\b| (Backspace), |\a| (Alarm), |\e|
  191. (Escape), |\033|(octal), |\x1b|(hex), |\c[| (control).
  192. \newline |\l| and |\u| lowcase/upcase the following character; 
  193. \newline |\L| and |\U| lowcase/upcase until a |\E| is encountered.
  194.  
  195.  
  196. \hangindent=2cm\hangafter=1
  197. \makebox[1cm]{}|`|<command>|`|
  198. evaluates to the output of the <command>. 
  199. \newline Also: |qx/|<command>|/|.
  200.  
  201. \hangindent=1cm\hangafter=1
  202. Array: |(1,2,3)|. |()| is an empty array.  
  203. \newline Also: |($a,$b,@rest) = (1,2,...);|
  204. \newline |(1..4)| is the same as |(1,2,3,4)|. Likewise |('abc'..'ade')|
  205.  
  206. \hangindent=1cm\hangafter=1
  207. Associative array:
  208. |(|<key1>|,|<val1>|,|<key2>|,|<val2>|,...)|
  209.  
  210. \hangindent=1cm\hangafter=1
  211. Filehandles: 
  212. \newline Pre-defined: |<STDIN>|, |<STDOUT>|, |<STDERR>|, |<ARGV>|,
  213. |<DATA>|;
  214. \newline User-specified: |<|<handle>|>|, |<$|<var>|>|.
  215. \newline |<>| is the input stream formed by the files specified in
  216. |@ARGV|, or standard input if no arguments are supplied.
  217.  
  218. \hangindent=1cm\hangafter=1
  219. Globs: |<|<pattern>|>| evaluates to all filenames according
  220. to the pattern.
  221. \newline Use |<${|<var>|}>| to glob from a variable.
  222.  
  223. \hangindent=1cm\hangafter=1
  224. Here-Is: |<<|<identifier>
  225. \newline {\it See the manual for details}
  226.  
  227. \hangindent=1cm\hangafter=1
  228. Special tokens:
  229. \newline \_\,\_|FILE|\_\,\_: filename; \_\,\_|LINE|\_\,\_: line number.
  230. \newline \_\,\_|END|\_\,\_: end of program; remaining lines can be read using
  231. \<<data>\>.
  232. \section{Variables} 
  233.  
  234. \begin{enum}{3.2cm}
  235.  
  236. \Xi{|\$var|} a simple scalar variable
  237.  
  238. \Xi{|\$var[28]|} 29th element of array |@var| (the |[]| are
  239. part of it)
  240.  
  241. \Xi{|\$var\{'Feb'\}|} one value from associative array |%var|
  242.  
  243. \Xi{|\$\#var|} last index of array |@var|
  244.  
  245. \Xi{|@var|} the entire array;
  246.  
  247. in scalar context: the number of elements in the array
  248.  
  249. \Xi{|@var[3,4,5]|} a slice of the array |@var|
  250.  
  251. \Xi{|@var\{'a','b'\}|} a slice of |%var|; same as
  252. |($var{'a'},$var{'b'})|
  253.  
  254. \Xi{|\%var|} the entire associative array
  255.  
  256. \Xi{|\$var\{'a',1,...\}|} emulates a multi-dimensional array
  257.  
  258. \Xi{|('a'..'z')[4,7,9]|} a slice of an array literal
  259.  
  260. \Xi{|*|<name>} refers to all objects represented by <name>.
  261. ``|*name1 = *name2|'' makes |name1| a reference to |name2|.
  262.  
  263. \end{enum}
  264. \section{Statements} 
  265.  
  266. Every statement is an expression, optionally followed by a modifier,
  267. and terminated by a semi-colon.
  268.  
  269. Execution of expressions can depend on other expressions using one of
  270. the modifiers \kwd{if}, \kwd{unless}, \kwd{while} or \kwd{until},
  271. e.g.:
  272.  
  273. \quad    <expr1> \kwd{if} <expr2> |;| \\
  274. \quad    <expr1> \kwd{until} <expr2> |;|
  275.  
  276. Also, by using one of the logical operators \|\|, |&&| or |? :|, e.g.:
  277.  
  278. \quad    <expr1> \|\| <expr2> |;| \\
  279. \quad    <expr1> |?| <expr2> |:| <expr3> |;| 
  280.  
  281. Statements can be combined to form a <block> when enclosed in |{}|.
  282.  
  283. Compound statements may be used to control flow:
  284.  
  285. \quad    \kwd{if} |(|<expr>|)| <block> [ [ \kwd{elsif}
  286.     |(|<expr>|)| <BLOCK ...> ] \kwd{else}
  287.     <block> ]
  288. \\
  289. \quad    \kwd{unless} |(|<expr>|)| <block> [ \kwd{else}
  290.     <block> ]
  291. \\
  292. \quad    [ <label>\kwd{:} ] \kwd{while} |(|<expr>|)|
  293.     <block> [ \kwd{continue} <block> ]
  294. \\
  295. \quad    [ <label>\kwd{:} ] \kwd{until} |(|<expr>|)|
  296.     <block> [ \kwd{continue} <block> ]
  297. \\
  298. \quad    [ <label>\kwd{:} ] \kwd{for} |(|<expr>|;|
  299.     <expr>|;| <expr>|)| <block>
  300. \\
  301. \quad    [ <label>\kwd{:} ] \kwd{foreach} <var>\dag
  302.     |(|<array>|)| <block>
  303. \\
  304. \quad    [ <label>\kwd{:} ] <block> [ \kwd{continue} < block> ]
  305.  
  306. Special forms are:
  307.  
  308. \quad    \kwd{do} <block> \kwd{while} <expr> |;| \\
  309. \quad    \kwd{do} <block> \kwd{until} <expr> |;| \\
  310.  
  311. which are guaranteed to perform <block> once before testing <expr>.
  312.  
  313. \section{Flow control} 
  314.  
  315. \begin{enum}{1cm}
  316.  
  317. \Xi{\kwd{do} <block>}
  318. Returns the value of the last command in the sequence of commands indicated by <block>. \kwd{next}, \kwd{last} and \kwd{redo}
  319.  cannot be used here.
  320.  
  321. \Xi{\kwd{do} <subroutine>\kwd{(LIST)}} 
  322. Executes a <subroutine> declared by a \kwd{sub} declaration, and
  323. returns the value of the last expression evaluated in <subroutine> .
  324. \newline Preferred form is: |&|<subroutine> .
  325.  
  326. \Xi{\kwd{do} <FILENAME>}
  327. Executes the contents of <filename> as a perl script. Errors are
  328. returned in |$@|.
  329. \newline Preferred form is: \kwd{require} <filename> .
  330.  
  331. \Xi{\kwd{goto} <label>}
  332. Continue execution at the specified label.
  333.  
  334. \Xi{\kwd{last} [<label>]}
  335. Immediately exits the loop in question. Skips continue block.
  336.  
  337. \Xi{\kwd{next} [<label>]}
  338. Starts the next iteration of the loop.
  339.  
  340. \Xi{\kwd{redo} [<label>]}
  341. Restarts the loop block without evaluating the conditional again.
  342.  
  343. \Xi{\kwd{return} <expr>}
  344. Returns from a subroutine with the value specified.
  345.  
  346. \end{enum}
  347. \section{Operators} 
  348.  
  349. \begin{tabbing}
  350. |    |\=|    |\= \kill
  351. |+ -| \> |* /| \> Addition, subtraction, multiplication, division. \\
  352. |%| \> \> Modulo division. \\
  353. \| \& \> \^ \> Bitwise or, bitwise and, bitwise exclusive or. \\
  354. |>>| \> |<<| \> Bitwise shift right, bitwise shift left. \\
  355. |**| \> \> Exponentiation. \\
  356. |.| \> \> Concatenation of two strings. \\
  357. \kwd{x} \> \> Returns a string or array consisting of the left operand
  358. (an array or \\
  359. \> \> a string) repeated the number of times specified by the right operand.
  360. \end{tabbing}
  361.  
  362. All of the above operators also have an assignment operator, e.g. ``|.=|''.
  363.  
  364. \begin{tabbing}
  365. |    |\=|    |\= \kill
  366. |++| \> |--| \> Auto-increment (magical on strings), auto-decrement. \\
  367. |? :|\>      \> Alternation (if-then-else) operator. \\
  368. \|\| \> \&\&   \> Logical or, logical and. \\
  369. |=|\,|=| \> |!=| \> Numeric equality, inequality. \\
  370. \kwd{eq} \> \kwd{ne} \> String equality, inequality. \\
  371. |<|  \>  |>|  \> Numeric less than, greater than. \\
  372. \kwd{lt} \> \kwd{gt} \> String less than, greater than. \\
  373. |<=| \> |>=| \> Numeric less (greater) than or equal to. \\
  374. \kwd{le} \> \kwd{ge} \> String less (greater) than or equal. \\
  375. |<=>| \> \> Numeric compare. Returns -1, 0 or 1. \\
  376. \kwd{cmp} \> \> String compare. Returns -1, 0 or 1. \\
  377. |=~| \> |!~| \> Search pattern, substitution, or translation (negated). \\
  378. |..| \> \> Enumeration, also input line range operator. \\
  379. |,| \> \> Comma operator.
  380. \end{tabbing}
  381. \section{File test operators} 
  382.  
  383. These unary operators takes one argument, either a filename or a
  384. filehandle, and tests the associated file to see if something is true
  385. about it. If the argument is omitted, tests |$_| (except for |-t,|
  386. which tests |STDIN|). If the special argument |_| (underscore) is
  387. passed, uses the info of the preceding test. 
  388.  
  389. \begin{enum}{2.5cm}
  390.  
  391. \Xi{|-r -w -x -o|}  File is readable/writable/executable/owned by
  392. effective uid. 
  393.  
  394. \Xi{|-R -W -X -O|}  File is readable/writable/executable/owned by real
  395. uid.  
  396.  
  397. \Xi{|-e  -z  -s|}  File exists / has zero/non-zero size. 
  398.  
  399. \Xi{|-f  -d|}  File is a plain file, a directory.
  400.  
  401. \Xi{|-l  -S  -p|}  File is a symbolic link, a socket, a named pipe (FIFO). 
  402.  
  403. \Xi{|-b  -c|}  File is a block/character special file. 
  404.  
  405. \Xi{|-u  -g  -k|}  File has setuid/setgid/sticky bit set. 
  406.  
  407. \Xi{|-t|}  Tests if filehandle (|STDIN| by default) is opened to a tty.
  408.  
  409. \Xi{|-T  -B|}  File is a text/non-text (binary) file.  |-T| and |-B|
  410. return TRUE on a null file, or a file at EOF when testing a filehandle. 
  411.  
  412. \Xi{|-M  -A  -C|}  File creation / access / inode change time. Measured
  413. in days since this program started. See also |$^T| in section
  414. ``Special~Variables''.
  415.  
  416. \end{enum}
  417. \makeuppage
  418. A <list> is a (possibly parenthesised) list of expressions, variables
  419. or <list>s. An array variable or an array slice may always be used
  420. instead of a <list>.  
  421.  
  422. \section{Arithmetic functions} 
  423.  
  424. \begin{enum}{1cm}
  425.  
  426. \Xi{\kwd{atan2(}<y>\kwd{,}<x>\kwd{)}}
  427. Returns the arctangent of <Y>/<X> in the range -$\pi$ to $\pi$.
  428.  
  429. \Xi{\kwd{cos(}\oEXPR \kwd{)}*}
  430. Returns the cosine of <expr> (expressed in radians).
  431.  
  432. \Xi{\kwd{exp(}\oEXPR \kwd{)}*}
  433. Returns |e| to the power of <expr>.
  434.  
  435. \Xi{\kwd{int(}\oEXPR \kwd{)}*}
  436. Returns the integer portion of <expr>.
  437.  
  438. \Xi{\kwd{log(}\oEXPR \kwd{)}*}
  439. Returns natural logarithm (base |e|) of <expr>.
  440.  
  441. \Xi{\kwd{rand}[\kwd{(}<expr>\kwd{)}*]}
  442. Returns a random fractional number between 0 and the value of <expr>.
  443. If <expr> is omitted, returns a value between 0 and 1. 
  444.  
  445. \Xi{\kwd{sin(}\oEXPR \kwd{)}*}
  446. Returns the sine of <expr> (expressed in radians).
  447.  
  448. \Xi{\kwd{sqrt(}\oEXPR \kwd{)}*}
  449. Return the square root of <expr>.
  450.  
  451. \Xi{\kwd{srand}[\kwd{(}<expr>\kwd{)}*]}
  452. Sets the random number seed for the rand operator.
  453.  
  454. \Xi{\kwd{time}}
  455. Returns the number of seconds since January 1, 1970. Suitable for
  456. feeding to \kwd{gmtime} and \kwd{localtime}. 
  457.  
  458. \end{enum}
  459. \section{Conversion functions} 
  460.  
  461. \begin{enum}{1cm}
  462.  
  463. \Xi{\kwd{gmtime(}<expr>\kwd{)}*}
  464. Converts a time as returned by the \kwd{time} function to a 9-element
  465. array (\$sec, \$min, \$hour, \$mday, \$mon, \$year, \$wday,
  466. \$yday, \$isdst) with the time analyzed for the Greenwich timezone.
  467. \$mon has the range 0..11 and \$wday has the range 0..6.
  468.  
  469. \Xi{\kwd{hex(}\oEXPR\kwd{)}*}
  470. Returns the decimal value of <expr> interpreted as an hex string.
  471.  
  472. \Xi{\kwd{localtime(}<expr>\kwd{)}*}
  473. Converts a time as returned by the \kwd{time} function to a 9-element
  474. array with the time analyzed for the local timezone. 
  475.  
  476. \Xi{\kwd{oct(}\oEXPR\kwd{)}*}
  477. Returns the decimal value of <expr> interpreted as an octal string. If
  478. <expr> starts off with |0x|, interprets it as a hex string instead.
  479.  
  480. \Xi{\kwd{ord(}\oEXPR\kwd{)}*}
  481. Returns the ascii value of the first character of <expr>.
  482.  
  483. \Xi{\kwd{vec(}<expr>\kwd{,}<offset>\kwd{,}<bits>\kwd{)}}
  484. Treats <expr> as a string of unsigned ints, and yields the bit at
  485. <offset>. <bits> must be between 1 and 32. May be used as an lvalue.
  486.  
  487. \end{enum}
  488. \section{Structure conversion} 
  489.  
  490. \begin{enum}{1cm}
  491.  
  492. \Xi{\kwd{pack(}<template>\kwd{,}<list>\kwd{)}}
  493. Packs the values into a binary structure using <template>.
  494.  
  495. \Xi{\kwd{unpack(}<template>\kwd{,}<expr>\kwd{)}}
  496. Unpacks the structure <expr> into an array, using <template>.
  497.  
  498. <template> is a sequence of characters as follows:
  499.  
  500. \begin{tabbing}
  501. |  |\=|a |\=|/ |\=|A  |\= \kill
  502.   \> |a| \> / \> |A| \> Ascii string, null / space padded \\
  503.   \> |b| \> / \> |B| \> Bit string in ascending / descending order \\
  504.   \> |c| \> / \> |C| \> Native / unsigned char value \\
  505.   \> |f| \> / \> |d| \> Single / double float in native format \\
  506.   \> |h| \> / \> |H| \> Hex string, low / high nybble first. \\
  507.   \> |i| \> / \> |I| \> Signed / unsigned integer value \\
  508.   \> |l| \> / \> |L| \> Signed / unsigned long value \\
  509.   \> |n| \> / \> |N| \> Short / long in network byte order \\
  510.   \> |s| \> / \> |S| \> Signed / unsigned short value \\
  511.   \> |u| \> / \> |p| \> Uuencoded string / Pointer to a string \\
  512.   \> |x| \> / \> |@| \> Null byte / null fill until position \\
  513.   \> |X| \>   \>     \> Backup a byte
  514. \end{tabbing}
  515.  
  516. Each character may be followed by a decimal number which will be used
  517. as a repeat count, an |*| specifies all remaining arguments. \\
  518. If the format is preceded with |%|<n>, \kwd{unpack} returns an
  519. <n>-bit checksum instead. \\
  520. Spaces may be included in the template for readability purposes.
  521.  
  522. \end{enum}
  523. \section{String functions} 
  524.  
  525. \begin{enum}{1cm}
  526.  
  527. \Xi{\kwd{chop(}<list>\dag\kwd{)}}
  528. Chops off the last character on all elements of the list; returns the
  529. last chopped character. The parentheses may be omitted if <list> is a
  530. single variable.
  531.  
  532. \Xi{\kwd{crypt(}<plaintext>\kwd{,}<salt>\kwd{)}}
  533. Encrypts a string.
  534.  
  535. \Xi{\kwd{eval(}\oEXPR \kwd{)}*}
  536. <expr> is parsed and executed as if it were a perl program. The value
  537. returned is the value of the last expression evaluated. If there is a
  538. syntax error or runtime error, an undefined string is returned by
  539. eval, and |$@| is set to the error message.
  540.  
  541. \Xi{\kwd{index(}<str>\kwd{,}<substr>[\kwd{,}<offset>]\kwd{)}}
  542. Returns the position of <substr> in <str> at or after <offset>. If the
  543. substring is not found, returns |$[-1|.
  544.  
  545. \Xi{\kwd{length(}\oEXPR\kwd{)}*}
  546. Returns the length in characters of the value of <expr>.
  547.  
  548. \Xi{\kwd{rindex(}<str>\kwd{,}<substr>[\kwd{,}<offset>]\kwd{)}}
  549. Returns the position of the last occurrence of <substr> in <str> at or
  550. before <offset>.
  551.  
  552. \Xi{\kwd{substr(}<expr>\kwd{,}<offset>[\kwd{,}<len>]\kwd{)}}
  553. Extracts a substring out of <expr> and returns it. If <offset>
  554. is negative, counts from the end of the string. May be used as an lvalue.
  555.  
  556. \end{enum}
  557. \section{Array and list functions} 
  558.  
  559. \begin{enum}{1cm}
  560.  
  561. \Xi{\kwd{delete} \$<array>\{<key>\}}
  562. Deletes the specified value from the specified associative array.
  563. Returns the deleted value. 
  564.  
  565. \Xi{\kwd{each(}|\%|<array>\kwd{)}*}
  566. Returns a 2-element array consisting of the key and value for the next
  567. value of an associative array. Entries are returned in an apparently
  568. random order. When the array is entirely read, a null array is
  569. returned. The next call to \kwd{each} after that will start iterating again.
  570.  
  571. \Xi{\kwd{grep(}<expr>\kwd{,}<list>\kwd{)}}
  572. Evaluates <expr> for each element of the <list>, locally setting |$_|
  573. to refer to the element. Modifying |$_| will modify the corresponding
  574. element from <list>. Returns array of elements from <list> for which
  575. <expr> returned true. 
  576.  
  577. \Xi{\kwd{join(}<expr>\kwd{,}<list>\kwd{)}}
  578. Joins the separate strings of <list> into a single string with fields
  579. separated by the value of <expr>, and returns the string.
  580.  
  581. \Xi{\kwd{keys(}|\%|<array>\kwd{)}*}
  582. Returns an array with of all the keys of the named
  583. associative array.
  584.  
  585. \Xi{\kwd{pop(}|@|<array>\kwd{)}*}
  586. Pops and returns the last value of the array, shortens the array by 1. 
  587.  
  588. \Xi{\kwd{push(}|@|<array>\kwd{,}<list>\kwd{)}}
  589. Pushes the values of <list> onto the end of <array>. The length of the
  590. array increases by the length of <list>.
  591.  
  592. \Xi{\kwd{reverse(}<list>\kwd{)}*}
  593. In array context: returns the <list> in reverse order. \\
  594. In scalar
  595. context: returns the first element of <list> with bytes reversed. 
  596.  
  597. \Xi{\kwd{shift}[\kwd{(}|@|<array>\kwd{)}*]}
  598. Shifts the first value of the array off and returns it, shortening the
  599. array by 1 and moving everything down. If |@|<array> is omitted, shifts
  600. |@ARGV| in main and |@_| in subroutines.  
  601.  
  602. \Xi{\kwd{sort(} [<subroutine> ] <list>\kwd{)}*}
  603. Sorts the <list> and returns the sorted array value. If <subroutine>
  604. is specified, gives the name of a subroutine that returns less than
  605. zero, zero, or greater than zero, depending on how the elements of the
  606. array, available to the routine as |$a| and |$b|, are to be ordered.
  607.  
  608. \Xi{\kwd{splice(}|@|<array>\kwd{,}<offset>[\kwd{,}<length>[\kwd{,}<list>]]\kwd{)}}
  609. Removes the elements of |@|<array> designated by <offset> and
  610. <length>, and replaces them with <list> (if specified). \\
  611. Returns the elements removed.
  612.  
  613. \Xi{\kwd{split}[\kwd{(}<pattern>[\kwd{,}\oEXPR [\kwd{,}<limit>]]\kwd{)}]}
  614. Splits a string into an array of strings, and returns it. If <limit>
  615. is specified, splits in no more than that many fields. If <pattern> is
  616. also omitted, splits on whitespace. If
  617. not in array context: returns number of fields and splits to |@_|.
  618. See also: ``Search and Replace Functions''. 
  619.  
  620. \Xi{\kwd{unshift(}|@|<array>\kwd{,}<list>\kwd{)}}
  621. Prepends list to the front of the array, and returns the number of
  622. elements in the new array.
  623.  
  624. \Xi{\kwd{values(}|\%|<array>\kwd{)}*}
  625. Returns a normal array consisting of all the values of the named
  626. associative array. 
  627.  
  628. \end{enum}
  629.  
  630.  
  631. \section{File operations} 
  632.  
  633. Functions operating on a list of files return the number of files
  634. successfully operated upon.
  635.  
  636. \begin{enum}{1cm}
  637.  
  638. \Xi{\kwd{chmod(}<list>\kwd{)}*}
  639. Changes the permissions of a list of files. The first element of the
  640. list must be the numerical mode. 
  641.  
  642. \Xi{\kwd{chown(}<list>\kwd{)}*}
  643. Changes the owner and group of a list of files. The first two elements
  644. of the list must be the numerical uid and gid. 
  645.  
  646. \Xi{\kwd{truncate(}<file>\kwd{,}<size>\kwd{)}}
  647. truncates <file> to <size>. <file> may be a filename or a filehandle.
  648.  
  649. \Xi{\kwd{link(}<oldfile>\kwd{,}<newfile>\kwd{)}}
  650. Creates a new filename linked to the old filename.
  651.  
  652. \Xi{\kwd{lstat(}<file>\kwd{)}}
  653. Like stat, but does not traverse a final symbolic link.
  654.  
  655. \Xi{\kwd{mkdir(}<dir>\kwd{,}<mode>\kwd{)}}
  656. Creates a directory with given permissions. Sets |$!| on failure.
  657.  
  658. \Xi{\kwd{select(}<rbits>\kwd{,}<wbits>\kwd{,}<nbits>\kwd{,}<timeout>\kwd{)}}
  659. Performs a {\it select\/}(2) system call with the same parameters.
  660.  
  661. \Xi{\kwd{readlink(}\oEXPR\kwd{)}*}
  662. Returns the value of a symbolic link.
  663.  
  664. \Xi{\kwd{rename(}<oldname>\kwd{,}<newname>\kwd{)}}
  665. Changes the name of a file.
  666.  
  667. \Xi{\kwd{rmdir(}<filename>\dag\kwd{)}*}
  668. Deletes the directory if it is empty. Sets |$!| on failure.
  669.  
  670. \Xi{\kwd{stat(}<file>\kwd{)}}
  671. Returns a 13-element array (\$dev, \$ino, \$mode, \$nlink, \$uid, \$gid,
  672. \$rdev, \$size, \$atime, \$mtime, \$ctime, \$blksize, \$blocks). <file> can
  673. be a filehandle, an expression evaluating to a filename, or |_| to
  674. refer to the last file test operation. 
  675.  
  676. \Xi{\kwd{symlink(}<oldfile>\kwd{,}<newfile>\kwd{)}}
  677. Creates a new filename symbolically linked to the old filename.
  678.  
  679. \Xi{\kwd{unlink(}<list>\kwd{)}*}
  680. Deletes a list of files.
  681.  
  682. \Xi{\kwd{utime(}<list>\kwd{)}*}
  683. Changes the access and modification times. The first two elements of
  684. the list must be the numerical access and modification times.
  685.  
  686. \end{enum}
  687.  
  688.  
  689. \makeuppage
  690. \section{Directory reading routines} 
  691.  
  692. \begin{enum}{1cm}
  693.  
  694. \Xi{\kwd{closedir(}<dirhandle>\kwd{)}*}
  695. Closes a directory opened by opendir.
  696.  
  697. \Xi{\kwd{opendir(}<dirhandle>\kwd{,}<dirname>\kwd{)}}
  698. Opens a directory on the handle specified.
  699.  
  700. \Xi{\kwd{readdir(}<dirhandle>\kwd{)}*}
  701. Returns the next entry (or an array of entries) in the directory.
  702.  
  703. \Xi{\kwd{rewinddir(}<dirhandle>\kwd{)}*}
  704. Positions the directory to the beginning.
  705.  
  706. \Xi{\kwd{seekdir(}<dirhandle>\kwd{,}<pos>\kwd{)}}
  707. Sets position for readdir on the directory.
  708.  
  709. \Xi{\kwd{telldir(}<dirhandle>\kwd{)}*}
  710. Returns the postion in the directory.
  711.  
  712. \end{enum}
  713. \section{Input / Output} 
  714.  
  715. In input/output operations, <filehandle> may be a filehandle as opened
  716. by the \kwd{open} operator, or a scalar variable which evaluates to
  717. the name of a filehandle to be used.  
  718.  
  719. \begin{enum}{1cm}
  720.  
  721. \Xi{\kwd{binmode(}<filehandle>\kwd{)}*}
  722. Arranges for the file opened on <filehandle> to be read in ``binary''
  723. mode as opposed to ``text'' mode (MS-DOS only). 
  724.  
  725. \Xi{\kwd{close(}<filehandle>\kwd{)}*}
  726. Closes the file or pipe associated with the file handle.
  727.  
  728. \Xi{\kwd{dbmclose(}|\%|<array>\kwd{)}*}
  729. Breaks the binding between the array and the dbm file.
  730.  
  731. \Xi{\kwd{dbmopen(}|\%|<array>\kwd{,}<dbmname>\kwd{, }<mode>\kwd{)}}
  732. Binds a dbm or ndbm file to the associative array. If the database
  733. does not exist, it is created with the indicated mode. 
  734.  
  735. \Xi{\kwd{eof(}<filehandle>\kwd{)}}
  736. Returns 1 if the next read will return end of file, or if the file is
  737. not open. 
  738.  
  739. \Xi{\kwd{eof}}
  740. Returns the eof status for the last file read.
  741.  
  742. \Xi{\kwd{eof( )}}
  743. Indicates eof on the pseudo file formed of the files listed on the
  744. command line. 
  745.  
  746. \Xi{\kwd{fcntl(}<filehandle>\kwd{,}<function>\kwd{,}|\$|<var>\kwd{)}}
  747. Implements the {\it fcntl\/}(2) function. This function has non-standard
  748. return values. See the manual for details. 
  749.  
  750. \Xi{\kwd{fileno(}<filehandle>\kwd{)}*}
  751. Returns the file descriptor for a given (open) file.
  752.  
  753. \Xi{\kwd{flock(}<filehandle>\kwd{,}<operation>\kwd{)}}
  754. Calls {\it flock\/}(2) on the file. <operation> adds from 1 (shared), 2
  755. (exclusive), 4 (non-blocking) or 8 (unlock). 
  756.  
  757.  
  758. \Xi{\kwd{getc}[\kwd{(}<filehandle>\kwd{)}*]}
  759. Yields the next character from the file, or |""| on EOF. If
  760. <filehandle> is omitted, reads from |STDIN|. 
  761.  
  762. \Xi{\kwd{ioctl(}<filehandle>\kwd{,}<function>\kwd{,}|\$|<var>\kwd{)}}
  763. performs {\it ioctl}(2) on the file. This function has non-standard
  764. return values. See the manual for details. 
  765.  
  766. \Xi{\kwd{open(}<filehandle>[\kwd{,}<filename>]\kwd{)}}
  767. Opens a file and associates it with <filehandle>. If <filename> is
  768. omitted, the scalar variable of the same name as the <filehandle> must
  769. contain the filename.
  770.  
  771. The following filename conventions apply when opening a file.
  772.  
  773. \begin{enum}{2cm}
  774. \Xi{|"|<file>|"|} open <file> for input. Also |"<|<file>|"|.
  775.  
  776. \Xi{|">|<file>|"|} open <file> for output, creating it if necessary.
  777.  
  778. \Xi{|">>|<file>|"|} open <file> in append mode.
  779.  
  780. \Xi{|"+>|<file>|"|} open <file> with read/write access.
  781.  
  782. \Xi{|"\||<cmd>|"|} opens a pipe to command <cmd>.
  783.  
  784. \Xi{|"|<cmd>|\|"|} opens a pipe from command <cmd>.
  785. \end{enum}
  786.  
  787. <file> may be |&|<filehnd> in which case the new file handle is
  788. connected to the (previously opened) filehandle <filehnd>.
  789.  
  790. \kwd{open} 
  791. returns 1 upon success, \kwd{undef} otherwise, except for pipes. The
  792. parentheses may be omitted, if only a <filehandle> is specified.
  793.  
  794. \Xi{\kwd{pipe(}<readhandle>\kwd{,}<writehandle>\kwd{)}}
  795. Returns a pair of connected pipes.
  796.  
  797. \Xi{\kwd{print}[\kwd{(}[<filehandle>]<list>\dag\kwd{)}*]}
  798. Prints a string or a comma-separated list of strings. If <filehandle>
  799. is omitted, prints by default to standard output (or to the last
  800. selected output channel - see \kwd{select}).  
  801.  
  802. \Xi{\kwd{printf}[\kwd{(}[<filehandle>] <list>\kwd{)}*]}
  803. Equivalent to \kwd{print} <filehandle> \kwd {sprintf(}<list>\kwd{)}.
  804.  
  805. \Xi{\kwd{read(}<filehandle>\kwd{,}|\$|<var>\kwd{,}<length>[\kwd{,}<offset>]\kwd{)}}
  806. Read <length> binary bytes from the file into the variable at
  807. <offset>. Returns number of bytes actually read. 
  808.  
  809. \Xi{\kwd{seek(}<filehandle>\kwd{,}<position>\kwd{,}<whence>\kwd{)}}
  810. Arbitrarily positions the file. Returns 1 upon success, 0 otherwise.
  811.  
  812. \Xi{\kwd{select}[\kwd{(}<filehandle>\kwd{)}}
  813. Sets the current default filehandle for output operations. Returns the
  814. previously selected filehandle. 
  815.  
  816. \Xi{\kwd{sprintf(}<format>\kwd{,}<list>\kwd{)}}
  817. Returns a string formatted by (almost all of) the usual printf
  818. conventions. 
  819.  
  820. \Xi{\kwd{sysread(}<filehandle>\kwd{,}|\$|<var>\kwd{,}<length>[\kwd{,}<offset>]\kwd{)}}
  821. Reads <length> bytes into |$|<var> at <offset>.
  822.  
  823. \Xi{\kwd{syswrite(}<filehandle>\kwd{,}<scalar>\kwd{,}<length>[\kwd{,}<offset>]\kwd{)}}
  824. Writes <length> bytes from <scalar> at <offset>.
  825.  
  826. \Xi{\kwd{tell}[\kwd{(}<filehandle>\kwd{)}]*}
  827. Returns the current file position for the file. If <filehandle> is
  828. omitted, assumes the file last read. 
  829.  
  830. \Xi{\kwd{write}[\kwd{(}<filehandle>\kwd{)}]*}
  831. Writes a formatted record to the specified file, using the format
  832. associated with that file. See ``Formats''. 
  833.  
  834. \end{enum}
  835. \makeuppage
  836. \section{Search and replace functions}
  837.  
  838. \begin{enum}{1cm}
  839.  
  840. \catcode`\~=\other
  841.  
  842. \Xi{[<expr> |=~|] [\kwd{m}]|/|<pattern>|/|[\kwd{g}][\kwd{i}][\kwd{o}]}
  843. Searches <expr> (default: |$_|) for a pattern. If you prepend an
  844. \kwd{m} you can use almost any pair of characters as delimiters. If
  845. used in array context, an array is returned consisting of the
  846. subexpressions matched by the parentheses in pattern, i.e.
  847. |($1,$2,$3,...)|.
  848. \\
  849. Optional modifiers: \kwd{g} matches as many times as possible; \kwd{i}
  850. searches in a case-insensitive manner; \kwd{o} interpolates variables
  851. only once.
  852. \\
  853. If <pattern> is empty, the most recent pattern from a
  854. previous match or replacement is used.
  855. \\
  856. With \kwd{g} the match can be used as an iterator in scalar context.
  857.  
  858. \Xi{|?|<pattern>|?|}
  859. This is just like the |/|<pattern>|/| search, except that it matches
  860. only once between calls to the reset operator. If <pattern> is empty,
  861. the most recent pattern from a previous match or replacement is used.
  862.  
  863. \Xi{[|\$|<var> |=~|] \kwd{s}|/|<pattern>|/|<replacement>|/|[\kwd{g}][\kwd{i}][\kwd{e}][\kwd{o}]}
  864. Searches a string for a pattern, and if found, replaces that pattern
  865. with the replacement text and returns the number of substitutions
  866. made. Otherwise it returns false. 
  867. \\
  868. Optional modifiers: \kwd{g} replaces all occurrences of the pattern;
  869. \kwd{e} interprets the replacement string as an expression; \kwd{i}
  870. and \kwd{o} as with |/|<pattern>|/| matching. Almost any delimiter may
  871. replace the slashes; if single quotes are used, no interpretation is
  872. done on the replacement string.
  873. \\
  874. If <pattern> is empty, the most recent pattern from a previous match or replacement is used.
  875.  
  876. \Xi{\kwd{study}[\kwd{(}|\$|<var>\dag\kwd{)}*]}
  877. Study the contents of |$|<var> in anticipation of doing many pattern
  878. matches on the contents before it is next modified.
  879.  
  880. \Xi{[|\$|<var> |=~|] \kwd{tr}|/|<searchlist>|/|<replacementlist>|/|[\kwd{c}][\kwd{d}][\kwd{s}]}
  881. Translates all occurrences of the characters found in the search list
  882. with the corresponding character in the replacement list. It returns
  883. the number of characters replaced. \kwd{y} may be used instead of \kwd{tr}. 
  884. \\
  885. Optional modifiers: \kwd{c} complements the <searchlist>; \kwd{d}
  886. deletes all characters not found in <searchlist>; \kwd{s} squeezes all
  887. sequences of characters that are translated into the same target
  888. character into one occurrence of this character.
  889.  
  890. \end{enum}
  891. \section{System interaction} 
  892.  
  893. \begin{enum}{1cm}
  894.  
  895. \Xi{\kwd{alarm(}<expr>\kwd{)}*}
  896. Schedules a |SIGALRM| to be delivered after <expr> seconds. 
  897.  
  898. \Xi{\kwd{chdir} [\kwd{(}<expr>\kwd{)}*]}
  899. Changes the working directory, |$ENV{"HOME"}| if <expr> is omitted.
  900.  
  901. \Xi{\kwd{chroot(}<filename>\dag\kwd{)}*}
  902. Changes the root directory for the process and its children.
  903.  
  904. \Xi{\kwd{die}[\kwd{(}<list>\kwd{)}*]}
  905. Prints the value of <list> to |STDERR| and exits with the current
  906. value of |$!| (errno). If |$!| is 0, exits with the value of |($? >> 8)|.
  907. If |($? >> 8)| is 0, exits with 255. <list> defaults to
  908. |"Died."|.
  909.  
  910. \Xi{\kwd{exec(}<list>\kwd{)}*}
  911. Executes the system command in <list>; does not return.
  912.  
  913. \Xi{\kwd{exit(}<expr>\kwd{)}*}
  914. Exits immediately with the value of |EXPR|.
  915.  
  916. \Xi{\kwd{fork}}
  917. Does a {\it fork\/}(2) system call. Returns the child pid to the parent
  918. process and zero to the child process. 
  919.  
  920. \Xi{\kwd{getlogin}}
  921. Returns the current login name as known by the system.
  922.  
  923. \Xi{\kwd{getpgrp}[\kwd{(}<pid>\kwd{)}*]}
  924. Returns the process group for process <pid> (0, or omitted,  means the
  925. current process). 
  926.  
  927. \Xi{\kwd{getppid}}
  928. Returns the process id of the parent process.
  929.  
  930. \Xi{\kwd{getpriority(}<which>\kwd{,}<who>\kwd{)}}
  931. Returns the current priority for a process, process group, or user.
  932.  
  933. \Xi{\kwd{kill(}<list>\kwd{)}*}
  934. Sends a signal to a list of processes. The first element of the list
  935. must be the signal to send (numeric, or its name as a string). 
  936.  
  937. \Xi{\kwd{setpgrp(}<pid>\kwd{,}<pgrp>\kwd{)}}
  938. Sets the process group for the <pid> (0 = current process).
  939.  
  940. \Xi{\kwd{setpriority(}<which>\kwd{,}<who>\kwd{,}<prio>\kwd{)}}
  941. Sets the current priority for a process, process group, or a user.
  942.  
  943. \Xi{\kwd{sleep}[\kwd{(}<expr>\kwd{)}*]}
  944. Causes the script to sleep for <expr> seconds, or forever if no
  945. <expr>. Returns the number of seconds actually slept. 
  946.  
  947. \Xi{\kwd{syscall(}<list>\kwd{)}*}
  948. Calls the system call specified in the first element of the list,
  949. passing the rest of the list as arguments to the call. 
  950.  
  951. \Xi{\kwd{system(}<list>\kwd{)}*}
  952. Does exactly the same thing as \kwd{exec }<list> except that a fork is
  953. done first, and the parent process waits for the child process to complete. 
  954.  
  955. \Xi{\kwd{times}}
  956. Returns a 4-element array (\$user, \$system, \$cuser, \$csystem) giving
  957. the user and system times, in seconds, for this process and the
  958. children of this process.  
  959.  
  960. \Xi{\kwd{umask}[\kwd{(}<expr>\kwd{)}*]}
  961. Sets the umask for the process and returns the old one. If <expr> is
  962. omitted, returns current umask value. 
  963.  
  964. \Xi{\kwd{wait}}
  965. Waits for a child process to terminate and returns the pid of the
  966. deceased process (-1 if none). The status is returned in |$?|. 
  967.  
  968. \Xi{\kwd{waitpid(}<pid>\kwd{,}<flags>\kwd{)}}
  969. Performs the same function as the corresponding system call.
  970.  
  971. \Xi{\kwd{warn(}<list>\kwd{)}*}
  972. Prints the message on |STDERR| like \kwd{die}, but doesn't exit.
  973.  
  974. \end{enum}
  975. \makeuppage
  976. \section{Networking} 
  977.  
  978. \begin{enum}{1cm}
  979.  
  980. \Xi{\kwd{accept(}<newsocket>\kwd{,}<genericsocket>\kwd{)}}
  981. Accepts a new socket.
  982.  
  983. \Xi{\kwd{bind(}<socket>\kwd{,}<name>\kwd{)}}
  984. Binds the <name> to the <socket>.
  985.  
  986. \Xi{\kwd{connect(}<socket>\kwd{,}<name>\kwd{)}}
  987. Connects the <name> to the <socket>.
  988.  
  989. \Xi{\kwd{getpeername(}<socket>\kwd{)}}
  990. Returns the socket address of the other end of the <socket>.
  991.  
  992. \Xi{\kwd{getsockname(}<socket>\kwd{)}}
  993. Returns the name of the socket.
  994.  
  995. \Xi{\kwd{getsockopt(}<socket>\kwd{,}<level>\kwd{,}<optname>\kwd{)}}
  996. Returns the socket options.
  997.  
  998. \Xi{\kwd{listen(}<socket>\kwd{,}<queuesize>\kwd{)}}
  999. Starts listening on the specified <socket>.
  1000.  
  1001. \Xi{\kwd{recv(}<socket>\kwd{,}<scalar>\kwd{,}<length>\kwd{,}<flags>\kwd{)}}
  1002. Receives a message on <socket>.
  1003.  
  1004. \Xi{\kwd{send(}<socket>\kwd{,}<msg>\kwd{,}<FLAGS[>\kwd{,}<to>]\kwd{)}}
  1005. Sends a message on the <socket>.
  1006.  
  1007. \Xi{\kwd{setsockopt(}<socket>\kwd{,}<level>\kwd{,}<optname>\kwd{,}<optval>\kwd{)}}
  1008. Sets the requested socket option.
  1009.  
  1010. \Xi{\kwd{shutdown(}<socket>\kwd{,}<how>\kwd{)}}
  1011. Shuts down a <socket>.
  1012.  
  1013. \Xi{\kwd{socket(}<socket>\kwd{,}<domain>\kwd{,}<type>\kwd{,}<protocol>\kwd{)}}
  1014. Creates a <socket> in <domain> with <type> and <protocol>.
  1015.  
  1016. \Xi{\kwd{socketpair(}<socket1>\kwd{,}<socket2>\kwd{,}<domain>\kwd{,}<type>\kwd{,}<protocol>\kwd{)}}
  1017. As socket, but creates a pair of bi-directional sockets.
  1018.  
  1019. \end{enum}
  1020. \section{SystemV IPC} 
  1021.  
  1022. The following functions all perform the same action as the
  1023. corresponding system calls.
  1024.  
  1025. \kwd{msgctl(}<id>\kwd{,}<cmd>\kwd{,}<args>\kwd{)} \\
  1026. \kwd{msgget(}<key>\kwd{,}<flags>\kwd{)} \\
  1027. \kwd{msgsnd(}<id>\kwd{,}<msg>\kwd{,}<flags>\kwd{)} \\
  1028. \kwd{msgrcv(}<id>\kwd{,}\$<var>\kwd{,}<size>\kwd{,}<type>\kwd{,}<flags>\kwd{)} \\
  1029. \kwd{semctl(}<id>\kwd{,}<semnum>\kwd{,}<cmd>\kwd{,}<arg>\kwd{)} \\
  1030. \kwd{semget(}<key>\kwd{,}<nsems>\kwd{,}<size>\kwd{,}<flags>\kwd{)} \\
  1031. \kwd{semop(}<key>\kwd{,}...\kwd{)} \\
  1032. \kwd{shmctl(}<id>\kwd{,}<cmd>\kwd{,}<arg>\kwd{)} \\
  1033. \kwd{shmget(}<key>\kwd{,}<size>\kwd{,}<flags>\kwd{)} \\
  1034. \kwd{shmread(}<id>\kwd{,}\$<var>\kwd{,}<pos>\kwd{,}<size>\kwd{)} \\
  1035. \kwd{shmwrite(}<id>\kwd{,}<string>\kwd{,}<pos>\kwd{,}<size>\kwd{)}
  1036. \makeuppage
  1037. \section{Miscellaneous} 
  1038.  
  1039. \begin{enum}{1cm}
  1040.  
  1041. \Xi{\kwd{caller}[\kwd{(}<expr>\kwd{)}]}
  1042. Returns an array (\$package,\$file,\$line,...) for a specific subroutine
  1043. call. ``|caller|'' returns this info for the current subroutine,
  1044. ``|caller(1)|'' for the caller of this subroutine etc..  
  1045.  
  1046. \Xi{\kwd{defined(}<expr>\kwd{)}*}
  1047. Tests whether the lvalue <expr> has a real value.
  1048.  
  1049. \Xi{\kwd{dump} [<label>]}
  1050. Immediate core dump. When reincarnated, starts at <label>.
  1051.  
  1052. \Xi{\kwd{local(}<list>\kwd{)}}
  1053. Creates a scope for the listed variables local to the enclosing block,
  1054. subroutine or eval. 
  1055.  
  1056. \Xi{\kwd{package} <name>}
  1057. Designates the remainder of the current block as a package.
  1058.  
  1059. \Xi{\kwd{require(}\oEXPR\kwd{)}*}
  1060. Includes the specified file from the perl library. Does not include
  1061. more than once, and yields a fatal error if the file does include not OK. 
  1062.  
  1063. \Xi{\kwd{reset} [\kwd{(}<expr>\kwd{)}*]}
  1064. Resets |??| searches so that they work again. <expr> is a list of
  1065. single letters. All variables and arrays beginning with one of those
  1066. letters are reset to their pristine state.  Only affects the current
  1067. package.
  1068.  
  1069. \Xi{\kwd{scalar(}<expr>\kwd{)}}
  1070. Forces evaluation of <expr> in scalar context.
  1071.  
  1072. \Xi{\kwd{sub} <name> \{ <expr> |;| ... \}}
  1073. Designates <name> as a subroutine. Parameters are passed by reference
  1074. as array |@_|. Returns the value of the last expression evaluated. 
  1075.  
  1076. \Xi{\kwd{undef}[\kwd{(}<lvalue>\kwd{)}*]}
  1077. Undefines the <lvalue>. Always returns the undefined value.
  1078.  
  1079. \Xi{\kwd{wantarray}}
  1080. Returns true if the current context expects an array value.
  1081.  
  1082. \end{enum}
  1083. \section{Formats} 
  1084.  
  1085. \kwd{format} [<name>] |=| \\
  1086. <formlist> \\
  1087. |.|
  1088.  
  1089. <formlist> pictures the lines, and contains the arguments which will
  1090. give values to the fields in the lines. Picture fields are:
  1091.  
  1092. |  @<<<...  | left adjusted field, repeat the |<| to denote the desired
  1093. width; \\
  1094. |  @>>>...  | right adjusted field; \\
  1095. |  @|\|\|\||...  | centered field; \\
  1096. |  @#.##... | numeric format with implied decimal point; \\
  1097. |  @*       | a multi-line field.
  1098.  
  1099. Use \^ instead of |@| for multi-line block filling.
  1100.  
  1101. Use |~| at the beginning of a line to suppress unwanted empty lines.
  1102.  
  1103. Use |~~| at the beginning of a line to have this format line repeated
  1104. until all fields are exhausted. 
  1105.  
  1106. Use |$-| to zero to force a page break.
  1107.  
  1108. See also |$|\^, |$~|, |$-| and |$=| in section ``Special Variables''.
  1109. \section{Info from system files} 
  1110.  
  1111. {\xiipt\sl passwd} \\
  1112. Info is (\$name, \$passwd, \$uid, \$gid, \$quota, \$comment, \$gcos, \$dir, \$shell).
  1113.  
  1114. \begin{enum}{6cm}
  1115.  
  1116. \Xi{\kwd{endpwent}}    Ends lookup processing.
  1117.  
  1118. \Xi{\kwd{getpwent}}    Gets next info.
  1119.  
  1120. \Xi{\kwd{getpwnam(}<name>\kwd{)}}    Gets info by name. 
  1121.  
  1122. \Xi{\kwd{getpwuid(}<uid>\kwd{)}}    Gets info by uid.
  1123.  
  1124. \Xi{\kwd{setpwent}}    Resets lookup processing.
  1125.  
  1126. \end{enum}
  1127.  
  1128. {\vskip6pt\xiipt\sl group} \\
  1129. Info is a 4-item array: (\$name, \$passwd, \$gid, \$members).
  1130.  
  1131. \begin{enum}{6cm}
  1132.  
  1133. \Xi{\kwd{endgrent}}    Ends lookup processing.
  1134.  
  1135. \Xi{\kwd{getgrgid(}<gid>\kwd{)}}    Gets info by group id. 
  1136.  
  1137. \Xi{\kwd{getgrnam(}<name>\kwd{)}}    Gets info by name.
  1138.  
  1139. \Xi{\kwd{getgrent}}    Gets next info.
  1140.  
  1141. \Xi{\kwd{setgrent}}    Resets lookup processing.
  1142.  
  1143. \end{enum}
  1144.  
  1145. {\vskip6pt\xiipt\sl hosts} \\
  1146. Info is (\$name, \$aliases, \$addrtype, \$length, @addrs).
  1147.  
  1148. \begin{enum}{6cm}
  1149.  
  1150. \Xi{\kwd{endhostent}}    Ends lookup processing.
  1151.  
  1152. \Xi{\kwd{gethostbyname(}<name>\kwd{)}}    Gets info by name.
  1153.  
  1154. \Xi{\kwd{gethostent}}    Gets next info.
  1155.  
  1156. \Xi{\kwd{sethostent(}<stayopen>\kwd{)}}    Resets lookup processing.
  1157.  
  1158. \end{enum}
  1159.  
  1160. {\vskip6pt\xiipt\sl networks} \\
  1161. Info is (\$name, \$aliases, \$addrtype, \$net).
  1162.  
  1163. \begin{enum}{6cm}
  1164.  
  1165. \Xi{\kwd{endnetent}}    Ends lookup processing.
  1166.  
  1167. \Xi{\kwd{getnetbyaddr(}<addr>\kwd{,}<type>\kwd{)}}    Gets info by address and type.
  1168.  
  1169. \Xi{\kwd{getnetbyname(}<name>\kwd{)}}    Gets info by name.
  1170.  
  1171. \Xi{\kwd{getnetent}}    Gets next info.
  1172.  
  1173. \Xi{\kwd{setnetent(}<stayopen>\kwd{)}}    Resets lookup processing.
  1174.  
  1175. \end{enum}
  1176.  
  1177. {\vskip6pt\xiipt\sl services} \\
  1178. Info is (\$name, \$aliases, \$port, \$proto).
  1179.  
  1180. \begin{enum}{6cm}
  1181.  
  1182. \Xi{\kwd{endservent}}    Ends lookup processing.
  1183.  
  1184. \Xi{\kwd{getservbyname(}<name>\kwd{, }<proto>\kwd{)}}    Gets info by name. 
  1185.  
  1186. \Xi{\kwd{getservbyport(}<port>\kwd{, }<proto>\kwd{)}}    Gets info by port.
  1187.  
  1188. \Xi{\kwd{getservent}}    Gets next info.
  1189.  
  1190. \Xi{\kwd{setservent(}<stayopen>\kwd{)}}    Resets lookup processing.
  1191.  
  1192. \end{enum}
  1193.  
  1194. {\vskip6pt\xiipt\sl protocols} \\
  1195.  
  1196. Info is (\$name, \$aliases, \$proto).
  1197.  
  1198. \begin{enum}{6cm}
  1199.  
  1200. \Xi{\kwd{endprotoent}}    Ends lookup processing.
  1201.  
  1202. \Xi{\kwd{getprotobyname(}<name>\kwd{)}}    Gets info by name.
  1203.  
  1204. \Xi{\kwd{getprotobynumber(}<number>\kwd{)}}    Gets info by number.
  1205.  
  1206. \Xi{\kwd{getprotoent}}    Gets next info.
  1207.  
  1208. \Xi{\kwd{setprotoent(}<stayopen>\kwd{)}}    Resets lookup processing.
  1209.  
  1210. \end{enum}
  1211. \section{Regular expressions} 
  1212.  
  1213. Each character matches itself, unless it is one of the special
  1214. characters |+?.*()[]{}|\||\|.
  1215.  
  1216. \begin{enum}{1cm}
  1217.  
  1218. \Xj{|.|}
  1219. matches an arbitrary character, but not a newline.
  1220.  
  1221. \Xj{|(|\ldots|)|}
  1222. groups a series of pattern elements to a single element.
  1223.  
  1224. \Xj{|+|}
  1225. matches the preceding pattern element one or more times.
  1226.  
  1227. \Xj{|?|}
  1228. matches zero or one times.
  1229.  
  1230. \Xj{|*|}
  1231. matches zero or more times.
  1232.  
  1233. \Xj{\{<n>|,|<m>\}}
  1234. denotes the minimum <n> and maximum <m> match count. |{|<n>|}| means
  1235. exactly <n> times; |{|<n>|,}| means at least <n> times. 
  1236.  
  1237. \Xj{|\char`\[|\ldots|\char`\]|}
  1238. denotes a class of characters to match. |[|\^\ldots|]| negates the class.
  1239.  
  1240. \Xj{|(|\ldots\|\ldots\|\ldots|)|}
  1241. matches one of the alternatives.
  1242.  
  1243. \end{enum}
  1244.  
  1245. Non-alphanumerics can be escaped from their special meaning using a
  1246. |\|.
  1247.  
  1248. \begin{enum}{1cm}
  1249.  
  1250. \Xj{|\char`\\w|}
  1251. matches alphanumeric, including ``|_|'', |\W| matches non-alphanumeric.
  1252.  
  1253. \Xj{|\char`\\b|}
  1254. matches word boundaries, |\B| matches non-boundaries.
  1255.  
  1256. \Xj{|\char`\\s|}
  1257. matches whitespace, |\S| matches non-whitespace.
  1258.  
  1259. \Xj{|\char`\\d|}
  1260. matches numeric, |\D| matches non-numeric.
  1261.  
  1262. \Xj{|\char`\\n|, |\char`\\r|, |\char`\\f|, |\char`\\t| etc.} 
  1263. have their usual meaning.
  1264.  
  1265. \Xj{|\char`\\w|, |\char`\\s| and |\char`\\d|}
  1266.  may be used within character classes, |\b| denotes backspace in this context.
  1267.  
  1268. \Xj{|\char`\\1|\ldots|\char`\\9|}
  1269. refer to matched sub-expressions, grouped with |()|, inside
  1270. the match. 
  1271.  
  1272. \Xj{|\char`\\10|}
  1273. and up can also be used if the pattern
  1274. matches that many sub-expressions. 
  1275.  
  1276. \end{enum}
  1277.  
  1278. See also |$1|\ldots|$9|, |$+|, |$&|, |$`| and |$'| in section ``Special
  1279. Variables''.
  1280.  
  1281. \section{Special variables} 
  1282.  
  1283. The following variables are global and should be localized in subroutines:
  1284.  
  1285. \begin{enum}{1cm}
  1286.  
  1287. \Xi{|\char`\$\char`\_|}
  1288. The default input and pattern-searching space.
  1289.  
  1290. \Xi{|\char`\$\char`\.|}
  1291. The current input line number of the last filehandle that was read.
  1292.  
  1293. \Xi{|\char`\$\char`\/|}
  1294. The input record separator, newline by default. May be multi-character.
  1295.  
  1296. \Xi{|\char`\$\char`\,|}
  1297. The output field separator for the print operator.
  1298.  
  1299. \Xi{|\char`\$\char`\"|}
  1300. The separator which joins elements of arrays interpolated in strings.
  1301.  
  1302. \Xi{|\char`\$\char`\\|}
  1303. The output record separator for the print operator.
  1304.  
  1305. \Xi{|\char`\$\char`\#|}
  1306. The output format for printed numbers. Initial value is ``|%.20g|''.
  1307.  
  1308. \Xi{|\char`\$\char`\*|}
  1309. Set to 1 to do multiline matching within a string, 0 to assume strings
  1310. contain a single line. Default is 0. 
  1311.  
  1312. \Xi{|\char`\$\char`\?|}
  1313. The status returned by the last |`|<command>|`|, pipe close or
  1314. \kwd{system} operator. 
  1315.  
  1316. \Xi{|\char`\$\char`\]|}
  1317. The perl version string (as displayed with |perl -v|), or version number.
  1318.  
  1319. \Xi{|\char`\$\char`\[|}
  1320. The index of the first element in an array, and of the first character
  1321. in a substring. Default is 0. 
  1322.  
  1323. \Xi{|\char`\$\char`\;|}
  1324. The subscript separator for multi-dimensional array emulation. Default
  1325. is |"\034"|. 
  1326.  
  1327. \Xi{|\char`\$\char`\!|}
  1328. If used in a numeric context, yields the current value of errno. If
  1329. used in a string context, yields the corresponding error string. 
  1330.  
  1331. \Xi{|\char`\$\char`\@|}
  1332. The perl error message from the last eval or \kwd{do} <expr> command.
  1333.  
  1334. \Xi{|\char`\$\char`\:|}
  1335. The set of characters after which a string may be broken to fill
  1336. continuation fields (starting with ``|^|'') in a format. 
  1337.  
  1338. \Xi{|\char`\$\char`\0|}
  1339. The name of the file containing the perl script being executed. May be
  1340. assigned to. 
  1341.  
  1342. \Xi{|\char`\$\char`\$|}
  1343. The process number of the perl running this script. Altered (in the
  1344. child process) by \kwd{fork}. 
  1345.  
  1346. \Xi{|\char`\$\char`\<|}
  1347. The real uid of this process.
  1348.  
  1349. \Xi{|\char`\$\char`\>|}
  1350. The effective uid of this process. 
  1351.  
  1352. \Xi{|\char`\$\char`\(|}
  1353. The real gid of this process.
  1354.  
  1355. \Xi{|\char`\$\char`\)|}
  1356. The effective gid of this process.
  1357.  
  1358. \Xi{|\char`\$\char`\^D|}
  1359. The debug flags as passed to perl using |-D| .
  1360.  
  1361. \Xi{|\char`\$\char`\^F|}
  1362. The highest system file descriptor, ordinarily 2.
  1363.  
  1364. \Xi{|\char`\${\char`\^}I|}
  1365. In-place edit extension as passed to perl using |-i| .
  1366.  
  1367. \Xi{|\char`\$\char`\^P|}
  1368. Internal debugging flag.
  1369.  
  1370. \Xi{|\char`\$\char`\^T|}
  1371. The time (as delivered by \kwd{time}) when the program started. This
  1372. value is used by the file test operators ``|-M|'', ``|-A|'' and
  1373. ``|-C|''.
  1374.  
  1375. \Xi{|\char`\$\char`\^W|}
  1376. The value if the |-w| option as passed to perl.
  1377.  
  1378. \Xi{|\char`\$\char`\^X|}
  1379. The name by which this perl was invoked.
  1380.  
  1381. \end{enum}
  1382.  
  1383. The following variables are context dependent and need not be
  1384. localized:
  1385.  
  1386. \begin{enum}{1cm}
  1387.  
  1388. \Xi{|\char`\$\char`\%|}
  1389. The current page number of the currently selected output channel.
  1390.  
  1391. \Xi{|\char`\$\char`\=|}
  1392. The page length of the current output channel. Default is 60 lines.
  1393.  
  1394. \Xi{|\char`\$\char`\-|}
  1395. The number of lines left on the page.
  1396.  
  1397. \Xi{|\char`\$\char`\~|}
  1398. The name of the current report format.
  1399.  
  1400. \Xi{|\char`\$\char`\^|}
  1401. The name of the current top-of-page format.
  1402.  
  1403. \Xi{|\char`\$\char`\||}
  1404. If set to nonzero, forces a flush after every write or print on the
  1405. currently selected output channel. Default is 0. 
  1406.  
  1407. \Xi{|\char`\$ARGV|}
  1408. The name of the current file when reading from |<>| .
  1409. \end{enum}
  1410.  
  1411. The following variables are always local to the current block:
  1412.  
  1413. \begin{enum}{1cm}
  1414.  
  1415. \Xi{|\char`\$\char`\&|}
  1416. The string matched by the last pattern match.
  1417.  
  1418. \Xi{|\char`\$\char`\`|}
  1419. The string preceding what was matched by the last pattern match.
  1420.  
  1421. \Xi{|\char`\$\char`\'|}
  1422. The string following what was matched by the last pattern match. 
  1423.  
  1424. \Xi{|\char`\$\char`\+|}
  1425. The last bracket matched by the last search pattern.
  1426.  
  1427. \Xi{\$|1|\ldots\$|9|\ldots}
  1428. Contains the subpattern from the corresponding set of parentheses in
  1429. the last pattern matched. |$10|\ldots and up are only available if the
  1430. match contained that many sub-expressions. 
  1431.  
  1432. \end{enum}
  1433.  
  1434.  
  1435. \section{Special arrays} 
  1436.  
  1437. \begin{enum}{1.5cm}
  1438.  
  1439. \Xi{|@ARGV|}
  1440. Contains the command line arguments for the script (not including the command name).
  1441.  
  1442. \Xi{|@INC|}
  1443. Contains the list of places to look for perl scripts to be evaluated
  1444. by the \kwd{do} <filename> and \kwd{require} commands. 
  1445.  
  1446. \Xi{|@\char`\_|}
  1447. Parameter array for subroutines. Also used by \kwd{split} if not in
  1448. array context. 
  1449.  
  1450. \Xi{|\char`\%ENV|}
  1451. Contains the current environment.
  1452.  
  1453. \Xi{|\char`\%INC|}
  1454. List of files that have been \kwd{require}d or \kwd{do}ne.
  1455.  
  1456. \Xi{|\char`\%SIG|}Used to set signal handlers for various signals.
  1457.  
  1458. \end{enum}
  1459. \section{The perl debugger} 
  1460.  
  1461. The perl symbolic debugger is invoked with |perl -d|.
  1462.  
  1463. \begin{enum}{2.5cm}
  1464.  
  1465. \Xi{|h|}
  1466. Prints out a help message.
  1467.  
  1468. \Xi{|T|}
  1469. Stack trace.
  1470.  
  1471. \Xi{|s|}
  1472. Single steps.
  1473.  
  1474. \Xi{|n|}
  1475. Single steps around subroutine call.
  1476.  
  1477. \Xi{|r|}
  1478. Returns from the current subroutine.
  1479.  
  1480. \Xi{|c| [<line>]}
  1481. Continues (until <line>, or another breakpoint or exit).
  1482.  
  1483. \Xi{\fbox{<ret>}}
  1484. Repeats last |s| or |n|.
  1485.  
  1486. \Xi{|l| [<range>]}
  1487. Lists a range of lines. <range> may be a number, start-end,
  1488. start+amount, or a subroutine name. If omitted, lists next window. 
  1489.  
  1490. \Xi{|f| <file>}
  1491. Switches to <file> and start listing it.
  1492.  
  1493. \Xi{|-|}
  1494. Lists previous window.
  1495.  
  1496. \Xi{|w|}
  1497. Lists window around current line.
  1498.  
  1499. \Xi{|l| <sub>}
  1500. Lists the named <sub>routine.
  1501.  
  1502. \Xi{|/|<pattern>|/|}
  1503. Forward search for <pattern>.
  1504.  
  1505. \Xi{|?|<pattern>|?|}
  1506. Backward search for <pattern>.
  1507.  
  1508. \Xi{|L|}
  1509. Lists lines that have breakpoints or actions.
  1510.  
  1511. \Xi{|S|}
  1512. List the names of all subroutines.
  1513.  
  1514. \Xi{|t|}
  1515. Toggles trace mode.
  1516.  
  1517. \Xi{|b| [<line> [<condition>]]}
  1518. Sets breakpoint at <line>, default: current line.
  1519.  
  1520. \Xi{|b| <subname> [<condition>]}
  1521. Sets breakpoint at the subroutine.
  1522.  
  1523. \Xi{|S|}
  1524. Lists names of all subroutines.
  1525.  
  1526. \Xi{|d| [<line>]}
  1527. Deletes breakpoint at the given line.
  1528.  
  1529. \Xi{|D|}
  1530. Deletes all breakpoints.
  1531.  
  1532. \Xi{|a| <line command>}
  1533. Sets an action for line.
  1534.  
  1535. \Xi{|A|}
  1536. Deletes all line actions.
  1537.  
  1538. \Xi{|\char`\<| <command>}
  1539. Sets an action to be executed before every debugger prompt.
  1540.  
  1541. \Xi{|\char`\>| <command>}
  1542. Sets an action to be executed before every |s|, |c| or |n| command.
  1543.  
  1544. \Xi{|V| [<package> [<vars>] ]}
  1545. Lists all variables in a package. Default package is main.
  1546.  
  1547. \Xi{|X| [<vars>]}
  1548. Like |V|, but assumes current package.
  1549.  
  1550. \Xi{|!| [ [-]<number>]}
  1551. Redo a debugging command. Default is previous command.
  1552.  
  1553. \Xi{|H| [-<number>]}
  1554. Displays the last -<number> commands of more than one letter.
  1555.  
  1556. \Xi{|q|}
  1557. Quits. You may also use your \fbox{<eof>} character.
  1558.  
  1559. \Xi{<command>}
  1560. Executes <command> as a perl statement.
  1561.  
  1562. \Xi{|p| \oEXPR}
  1563. Prints <expr>.
  1564.  
  1565. \Xi{|=|< >[<alias value>]}
  1566. Sets alias, or lists current aliases.
  1567.  
  1568. \end{enum}
  1569. \newpage
  1570. \vfill \vfill \vfill
  1571. \makebox[\textwidth]{Perl Reference Guide Revision \perlrev \hfill
  1572. \copyright 1989,1990,1991 Johan Vromans}
  1573.  
  1574. \end{document}
  1575.